Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] Improve description of y_sort_enabled #90096

Merged

Conversation

AdriaandeJongh
Copy link
Contributor

Y-sorting is an incredibly important tool in non-tile-based 2D games, and I only truly understood Godot's robust implementation of it after wasting 2 days writing complex scripts to control Sprite offsets as I did not comprehend the description for y_sort_enabled. This PR aims to improve that description so that I can save others the experimentation.

In short:

  • I merged the two first sentences as they were saying the same thing twice.
  • I attempted to actually explain what disabling y-sorting does instead of stating the obvious 'if you disable this, you disable this.'
  • I rewrote the second part to clarify that disabling y-sorting essentially groups the nodes under the y position of the parent if the outermost parent is Y-sorted. This concept is in my opinion quite complex and I think the previous description failed to describe the affordance of that complexity, namely: you can turn y_sort_enabled on and off on selected nodes to group and Y-sort the entire scene in a smart way.
  • I added that Y-sorting only works if those nodes are on the same Z-index. I was a bit in doubt about adding this, as it makes the whole tooltip another two lines higher, but decided to add it because there is a relationship with Z-index that isn't explained anywhere else.

As a bonus, I also removed the redundant 'Z index' at the start of the description for z_index. If that should be a separate PR, let me know.

@AdriaandeJongh AdriaandeJongh requested a review from a team as a code owner April 1, 2024 12:11
@AdriaandeJongh AdriaandeJongh changed the title Improved description of CanvasItem.y_sort_enabled [Doc] Improved description of y_sort_enabled Apr 1, 2024
@AdriaandeJongh AdriaandeJongh changed the title [Doc] Improved description of y_sort_enabled [Doc] Improve description of y_sort_enabled Apr 1, 2024
@AThousandShips AThousandShips added this to the 4.x milestone Apr 1, 2024
@AdriaandeJongh
Copy link
Contributor Author

I did another iteration on the second sentence after a good nights sleep. The tricky part of that sentence is that it involves nodes 3 layers deep. I landed on using the example names 'A', 'B', and 'C1, 'C2', etc implying the node hierarchy so I could describe the hierarchy without extending the parents / children analogy to 'grandparent' or 'grandchildren'.

@akien-mga akien-mga modified the milestones: 4.x, 4.3 Apr 6, 2024
@akien-mga akien-mga merged commit ab39f4c into godotengine:master Apr 8, 2024
16 checks passed
@akien-mga
Copy link
Member

Thanks!

@AdriaandeJongh AdriaandeJongh deleted the improve-y-sort-description branch April 8, 2024 10:22
@AdriaandeJongh
Copy link
Contributor Author

Thank you for merging my first PR into Godot main!

@akien-mga
Copy link
Member

Ah I missed that this was your first - congrats! 🎉

@Mickeon Mickeon added cherrypick:4.1 Considered for cherry-picking into a future 4.1.x release cherrypick:4.2 Considered for cherry-picking into a future 4.2.x release labels Jul 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cherrypick:4.1 Considered for cherry-picking into a future 4.1.x release cherrypick:4.2 Considered for cherry-picking into a future 4.2.x release documentation enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants